feat(v2): support custom description for blog-only mode #2359

zxuqian · 2020-03-05T10:39:08Z

Motivation

In blog-only mode, the meta description is set to "Blog", which leads to poor SEO. The custom homepage under src/pages/index.js uses the value of a customFields.descriptionfield defined in docusaurus.config.js to display the description. In this PR, I use the same customFields.description config value for the BlogPostList component in the docusaurus-theme-classic theme.

Have you read the Contributing Guidelines on pull requests?

Yes.

Test Plan

In docusaurus.config.js, look at the customFields.description value：

customFields: {
    description:
      'An optimized site generator in React. Docusaurus helps you to move fast and write content. Build documentation websites, blogs, marketing pages, and more.',
  }

Set the site to blog-only mode by setting routeBasePath to '/' in presets

presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          path: '../website-1.x/blog',
          postsPerPage: 3,
          feedOptions: {
            type: 'all',
            copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`,
          },
        },
      },
    ],
  ]

Check rendered page, the meta description displays the description value defined in customFields:

Related PRs

(If this PR adds or changes functionality, please take some time to update the docs at https://github.com/facebook/docusaurus, and link to your PR here.)

docusaurus-bot · 2020-03-05T10:41:39Z

Deploy preview for docusaurus-2 ready!

Built with commit 77bacef

https://deploy-preview-2359--docusaurus-2.netlify.app

yangshun

This is not a good API design. We shouldn't use customFields for a first-class feature. I don't have a good way around this right now but using the siteConfig's description would be better. Ideally we allow setting it on the blog plugin but there's no easy way to pass data from the blog plugin to the front end right now.

zxuqian · 2020-03-06T01:42:39Z

OK. I will rename it to description and extract it from top level config (same level as title). This is what you mean, right😃?

Is it the ideal way to let the user write a description for each post at the header option in the markdown file, and set the whole site's description in the blog config under preset-classic?

zxuqian · 2020-03-06T07:30:14Z

Ideally we allow setting it on the blog plugin but there's no easy way to pass data from the blog plugin to the front end right now.

By examining the source code, I found that the components are dynamically loaded by their filenames. The metadata and items properties in blogListPaginated are written to a JSON file and then loaded in the ComponentCreator. The components routes are dynamically created and the ComponentCreator is called inside the dynamically created route.js file in the build folder. I think we can pass additional routeProps to the ComponentCreator.

Here I made some changes (I would consider they are a little bit big.., but you can help me to review it 🤔 ..), here is the description of the major changes I have made:

Here I added a second parameter routeProps in ComponentCreator, and pass it to the Component loaded:

function ComponentCreator(path, routeProps) {
    //...
    return <Component {...loadedModules} {...props} {...routeProps} />;

In the docusaurs/src/routes.ts, the generateRouteCode function, the routeConfig now added a new property called props, and it will be passed to ComponentCreator:

function generateRouteCode(routeConfig: RouteConfig): string {
    const {
      path: routePath,
      component,
      modules = {},
      routes,
      exact,
      props,
    } = routeConfig;
    //...
    return `
{
  path: '${routePath}',
  component: ComponentCreator('${routePath}'${
      props ? `, ${JSON.stringify(props)}` : ''
    }),
  ${exactStr}
  ${routesStr}
}`;
  }

When call addRoute in the docusaurus-plugin-content-blog/index.ts, pass the additional props to the routeConfig, here I'm using a blogSiteDescription which is extracted from the plugin configuration, and its default value is "Blog":

addRoute({
            path: permalink,
            component: blogListComponent,
            exact: true,
            modules: {...},
            props: {
              blogSiteDescription,
            },
          });

I would update the code, so you can have a review of it.

slorber · 2020-07-28T12:38:46Z

@zxuqian this feature makes sense to me, can you update your pr?

slorber

willing to merge but need:

rebase
remove the "routeProps" system (un-needed)
rename blogSiteDescription to blogDescription
document

slorber · 2020-07-28T12:43:28Z

packages/docusaurus-types/src/index.d.ts

@@ -149,6 +149,7 @@ export interface RouteConfig {
  routes?: RouteConfig[];
  exact?: boolean;
  priority?: number;
+  props?: object;


slorber · 2020-07-28T12:44:05Z

packages/docusaurus-plugin-content-blog/src/index.ts

@@ -43,6 +43,7 @@ const DEFAULT_OPTIONS: PluginOptions = {
  remarkPlugins: [],
  rehypePlugins: [],
  truncateMarker: /<!--\s*(truncate)\s*-->/, // Regex.
+  blogSiteDescription: 'Blog',


blogDescription seems a better name (+ we need documentation)

slorber · 2020-07-28T12:46:03Z

packages/docusaurus-plugin-content-blog/src/index.ts

@@ -285,6 +287,9 @@ export default function pluginContentBlog(
              }),
              metadata: aliasedSource(pageMetadataPath),
            },
+            props: {
+              blogSiteDescription,
+            },


you don't need that, you'll already receive metadata.blogDescription as props

Hi @slorber , I found that to use blogDescription in metadata, I still need to get it from options object and pass it to the metadata object here(about line 125):

metadata: { permalink: blogPaginationPermalink(page), page: page + 1, postsPerPage, totalPages: numberOfPages, totalCount, previousPage: page !== 0 ? blogPaginationPermalink(page - 1) : null, nextPage: page < numberOfPages - 1 ? blogPaginationPermalink(page + 1) : null, blogDescription: options.blogDescription, }

Could you tell me if this is the case? Thank you!

Yes, the blogDescription is a field on the plugin options

OK! Thanks.

slorber · 2020-07-28T12:46:22Z

packages/docusaurus-theme-classic/src/theme/BlogListPage/index.js

@@ -13,15 +13,14 @@ import BlogPostItem from '@theme/BlogPostItem';
 import BlogListPaginator from '@theme/BlogListPaginator';

 function BlogListPage(props) {
-  const {metadata, items} = props;
+  const {metadata, items, blogSiteDescription} = props;


use metadata.blogDescription

slorber · 2020-07-28T12:46:42Z

packages/docusaurus/src/server/routes.ts

-  component: ComponentCreator('${routePath}'),
+  component: ComponentCreator('${routePath}'${
+      props ? `, ${JSON.stringify(props)}` : ''
+    }),


slorber · 2020-07-28T12:46:47Z

packages/docusaurus/src/client/exports/ComponentCreator.js

@@ -77,7 +77,7 @@ function ComponentCreator(path) {

      const Component = loadedModules.component;
      delete loadedModules.component;
-      return <Component {...loadedModules} {...props} />;
+      return <Component {...loadedModules} {...props} {...routeProps} />;


slorber · 2020-07-28T12:47:00Z

website/docusaurus.config.js

@@ -51,6 +51,7 @@ module.exports = {
            type: 'all',
            copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`,
          },
+          blogSiteDescription: 'Test description....',


remove to be able to merge

Should I leave blogDescription inside blog config, or should I move it to the root?

No it's in the blog options, because a Docusaurus might support hosting multiple blogs in the future, each one having its own description

zxuqian · 2020-07-29T13:02:11Z

OK! I will update it

resolve conflicts

slorber

That looks good, just a few things to change

slorber · 2020-07-30T13:09:16Z

packages/docusaurus-plugin-content-blog/src/pluginOptionSchema.ts

@@ -20,6 +20,7 @@ export const DEFAULT_OPTIONS = {
  blogTagsListComponent: '@theme/BlogTagsListPage',
  blogPostComponent: '@theme/BlogPostPage',
  blogListComponent: '@theme/BlogListPage',
+  blogDescription: '',


Suggested change

blogDescription: '',

blogDescription: 'Blog',

Let's keep it retrocompatible, it displays Blog by default currently

slorber · 2020-07-30T13:12:55Z

packages/docusaurus-theme-classic/src/theme/BlogListPage/index.tsx

-    <Layout title={title} description="Blog">
-      <div className="container margin-vert--lg">
+    <Layout title={title} description={blogDescription}>
+      <div className="container margin-vert--xl">


Suggested change

<div className="container margin-vert--xl">

<div className="container margin-vert--lg">

It's not the purpose of this PR to change the design. I'm open to discussing this but in another PR.

I think it looks weird on mobile to have as much

oh! This might be accidentally merged from a conflict, I will correct it.

slorber · 2020-07-30T13:13:14Z

website/docs/blog.md

+      '@docusaurus/preset-classic',
+      {
+        blog: {
+          blogDescription: 'A docusuarus powered blog!',


Suggested change

blogDescription: 'A docusuarus powered blog!',

blogDescription: 'A docusaurus powered blog!',

slorber · 2020-07-30T13:13:30Z

website/docs/using-plugins.md

+        /**
+         * Blog page meta description for better SEO
+         */
+        blogDescription: '',


Suggested change

blogDescription: '',

blogDescription: 'Blog',

slorber · 2020-07-30T13:41:02Z

Looks good, ready to merge, thanks

zxuqian · 2020-07-30T13:50:00Z

No problem, and thank you for the reviews!

zxuqian requested review from lex111, wgao19 and yangshun as code owners March 5, 2020 10:39

facebook-github-bot added the CLA Signed Signed Facebook CLA label Mar 5, 2020

yangshun suggested changes Mar 5, 2020

View reviewed changes

zxuqian requested a review from yangshun March 6, 2020 15:21

yangshun added the pr: new feature This PR adds a new API or behavior. label Mar 7, 2020

slorber requested changes Jul 28, 2020

View reviewed changes

slorber marked this pull request as draft July 29, 2020 17:39

zxuqian and others added 5 commits July 30, 2020 12:51

feat: support custom description on blog page

093ca83

resolve conflicts

feat(v2): allow additional props to pass to route components

478f4fb

resolve conflicts

Update blogDescription feature

31d26f6

Update doc for blogDescription

8317fbc

Remove test blogDescription config

678fe67

zxuqian force-pushed the zxuqian-patch-1 branch from 9464c2f to 678fe67 Compare July 30, 2020 04:51

zxuqian marked this pull request as ready for review July 30, 2020 04:53

Fix blogDescription schema validation

373ccea

zxuqian requested review from slorber and removed request for wgao19 July 30, 2020 10:12

slorber requested changes Jul 30, 2020

View reviewed changes

Fix minor errors

77bacef

slorber merged commit 4af25cd into facebook:master Jul 30, 2020

slorber mentioned this pull request Oct 6, 2020

[v2] Blog home page support different meta title #3542

Closed

DeadEnglish mentioned this pull request Oct 10, 2020

feat(v2): add option for blog meta title #3571

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(v2): support custom description for blog-only mode #2359

feat(v2): support custom description for blog-only mode #2359

zxuqian commented Mar 5, 2020

docusaurus-bot commented Mar 5, 2020 •

edited

Loading

yangshun left a comment

zxuqian commented Mar 6, 2020 •

edited

Loading

zxuqian commented Mar 6, 2020 •

edited

Loading

slorber commented Jul 28, 2020

slorber left a comment

slorber Jul 28, 2020

slorber Jul 28, 2020

slorber Jul 28, 2020

zxuqian Jul 29, 2020

slorber Jul 29, 2020

zxuqian Jul 29, 2020

slorber Jul 28, 2020

slorber Jul 28, 2020

slorber Jul 28, 2020

slorber Jul 28, 2020

zxuqian Jul 29, 2020

slorber Jul 29, 2020

zxuqian commented Jul 29, 2020

slorber left a comment

slorber Jul 30, 2020

slorber Jul 30, 2020

zxuqian Jul 30, 2020

slorber Jul 30, 2020

slorber Jul 30, 2020

slorber commented Jul 30, 2020

zxuqian commented Jul 30, 2020

	<div className="container margin-vert--xl">
	<div className="container margin-vert--lg">

	blogDescription: 'A docusuarus powered blog!',
	blogDescription: 'A docusaurus powered blog!',

feat(v2): support custom description for blog-only mode #2359

feat(v2): support custom description for blog-only mode #2359

Conversation

zxuqian commented Mar 5, 2020

Motivation

Have you read the Contributing Guidelines on pull requests?

Test Plan

Related PRs

docusaurus-bot commented Mar 5, 2020 • edited Loading

yangshun left a comment

Choose a reason for hiding this comment

zxuqian commented Mar 6, 2020 • edited Loading

zxuqian commented Mar 6, 2020 • edited Loading

slorber commented Jul 28, 2020

slorber left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zxuqian commented Jul 29, 2020

slorber left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

slorber commented Jul 30, 2020

zxuqian commented Jul 30, 2020

docusaurus-bot commented Mar 5, 2020 •

edited

Loading

zxuqian commented Mar 6, 2020 •

edited

Loading

zxuqian commented Mar 6, 2020 •

edited

Loading